<HTML><HEAD><TITLE>source_open(+File, +OptionList, -SourcePos)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(source_processor)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>source_open(+File, +OptionList, -SourcePos)</H1>
Open an ECLiPSe source code file for subsequent processing
<DL>
<DT><EM>File</EM></DT>
<DD>Name of source file (Atom or string), or term of the form stream(Stream)
</DD>
<DT><EM>OptionList</EM></DT>
<DD>List of options, possibly empty
</DD>
<DT><EM>SourcePos</EM></DT>
<DD>Source position handle
</DD>
</DL>
<H2>Description</H2>
This predicates opens an ECLiPSe source file (or prepares and
    already opened stream) for subsequent reading with source_read/4.
    Compared to the standard primitives for reading from a file, this
    takes care of
    <UL>
    <LI>nesting of included files
    <LI>creating and keeping track of modules
    <LI>syntax settings
    <LI>comments (optional)
    <LI>changing the current directory to the opened file's directory
    <LI>handling of if-elif-else-endif directives
    </UL>
    OptionList can contain the following:
    <DL>
    <DT>keep_comments</DT>
	<DD>treat comments and spacing between source terms as data
	rather than ignoring it</DD>
    <DT>include_comment_files</DT>
	<DD>interpret the comment(include,Files) directive and include
	the contents of the given files, identical to an include(Files)
	directive. By default, these directives are ignored.</DD>
    <DT>ignore_conditionals</DT>
	<DD>Ignore any special meaning of conditional directives (if/1,
	elif/1, else/0, endif/0) and just return them as a source term.
	The default is to interpret these directives, including or
	excluding corresponding source parts accordingly, while removing
	the directives themselves</DD>
    <DT>with_annotations</DT>
	<DD>return an annotated source term with every source term
	(and do not return a separate variable list)</DD>
    <DT>no_macro_expansion</DT>
	<DD>do not expand term macros (e.g. with/2 and of/2)</DD>
    <DT>minimal_macro_expansion</DT>
	<DD>do not expand term macros except in :- directives</DD>
    <DT>no_clause_expansion</DT>
	<DD>do not expand clause macros (e.g. DCGs)</DD>
    <DT>goal_expansion</DT>
	<DD>do inline expansion of goals (only works if clause expansion
	is not disabled)</DD>
    <DT>recreate_modules</DT>
	<DD>erase and re-create module when encountering a module directive</DD>
    </DL>
    source_open/3 and source_read/4 maintain a 'current source position',
    which is a structure containing (among others) the following fields:
    <PRE>
    :- export struct(source_position(
	stream,			% Eclipse stream
	file,			% canonical file name
	line,			% integer
	offset,			% integer
	included_from,		% source_position or []
	module,			% current source module
	...
    )).
    </PRE>
    i.e. information about the module context and the precise location
    of a source term (e.g. for error messages).
    <P>
    If File is of the form stream(Stream), then the predicate expects
    Stream to be an already opened input stream. Correspondingly, the
    processed stream will not be closed at the end of source processing
    (unlike files).
    <P>
    
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H2>See Also</H2>
<A HREF="../../lib/source_processor/source_close-2.html">source_close / 2</A>, <A HREF="../../lib/source_processor/source_read-4.html">source_read / 4</A>
</BODY></HTML>
